Enforce public API docs inventory by harsh21234i · Pull Request #458 · reflex-dev/xy

harsh21234i · 2026-08-05T07:37:25Z

Closes #444

Summary

Centralize the public API inventory for components, factories, Chart methods, and Selection methods.
Remove duplicated hardcoded API lists from tests.
Validate that public API methods are documented.
Document chart view and selection methods, including Selection.rows().
Update make check-docs to run the actual documentation checks while keeping example checks separate.

Testing

uv run python scripts/check_public_api.py --skip-lazy-import-check
uv run python -m pytest -q tests/test_public_api.py tests/test_type_surface.py
uv run ruff check ...
git diff --check

Summary by CodeRabbit

New Features
- Added documentation for Selection.rows(limit=None), enabling access to selected rows with optional result limits.
- Added guidance for controlling chart views, applying and clearing selections, and reading chart state.
Documentation
- Clarified notebook display behavior and requirements for Python callbacks.
- Improved documentation quality checks, including quickstart validation, formatting, linting, and spelling verification.
Tests
- Expanded coverage for public API and documentation consistency.

coderabbitai · 2026-08-05T07:37:44Z

Warning

Review limit reached

@harsh21234i, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 4 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5ef7406c-467d-4563-8fb0-8d38519f19cc

📥 Commits

Reviewing files that changed from the base of the PR and between 5832887 and 8f45166.

📒 Files selected for processing (6)

docs/api-reference/figure-methods.md
scripts/check_public_api.py
scripts/verify_docs_local.py
tests/_public_api_test_utils.py
tests/test_public_api.py
tests/test_type_surface.py

📝 Walkthrough

Walkthrough

The change adds runtime public API discovery and documentation coverage checks, documents Chart and Selection APIs, and introduces a local documentation verification workflow separate from example checks.

Changes

API inventory and documentation checks

Layer / File(s)	Summary
Runtime public API inventory `scripts/check_public_api.py`, `tests/test_public_api.py`, `tests/test_type_surface.py`	Runtime discovery classifies public component factories and discovers `Chart` and `Selection` methods. Tests use the generated inventory and validate return types and API contracts.
API documentation coverage `docs/api-reference/events-and-callbacks.md`, `docs/api-reference/figure-methods.md`, `scripts/check_public_api.py`, `tests/test_public_api.py`, `tests/test_type_surface.py`	The documentation covers `Selection.rows`, Chart view and selection methods, notebook display behavior, and callback requirements. Tests validate documentation coverage and the `Selection.rows` type surface.
Local documentation verification workflow `scripts/verify_docs_local.py`, `scripts/verify_local.py`, `Makefile`	The docs verifier runs tests, quickstart checks, Ruff formatting and linting, and codespell. `check-docs` invokes this workflow separately from `check-examples`.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Makefile
  participant verify_local
  participant verify_docs_local
  participant DocsApp
  Makefile->>verify_local: run docs check
  verify_local->>verify_docs_local: invoke documentation verifier
  verify_docs_local->>DocsApp: run docs tests and quality checks
  DocsApp-->>verify_docs_local: return status

Possibly related PRs

reflex-dev/xy#451: Both changes extend public API validation and related tests.

Suggested reviewers: alek99

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: enforcing documentation coverage through a public API inventory.
Linked Issues check	✅ Passed	The changes satisfy the linked issue objectives for API inventory, classification, documentation coverage, test deduplication, and separate docs checks [`#444`].
Out of Scope Changes check	✅ Passed	The changes remain within the linked issue scope and support public API validation, documentation coverage, and documentation quality checks.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

greptile-apps · 2026-08-05T07:39:38Z

Greptile Summary

The PR centralizes the supported component and method inventory, checks API-reference coverage, and separates documentation verification from example checks.

Adds discovery and manifest validation for component factories, Chart methods, and Selection methods.
Adds documentation for chart view/selection APIs and Selection.rows().
Introduces a dedicated local documentation gate and updates API-surface tests to consume the shared inventory.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/check_public_api.py	Centralizes API discovery and manifest comparison, then validates public Chart and Selection methods against API-reference documentation.
scripts/verify_docs_local.py	Adds the documentation verification sequence covering dependency sync, docs tests, API inventory, quickstart validation, formatting, linting, and spelling.
scripts/verify_local.py	Registers the new documentation verification sequence as the `docs` check group.
tests/test_public_api.py	Reworks checker fixtures around discovered API categories and adds manifest and documentation-coverage tests.
tests/test_type_surface.py	Replaces duplicated API lists with the centralized inventory and extends type-surface coverage to support factories and Selection rows.
docs/api-reference/figure-methods.md	Documents notebook display behavior and the public chart view and selection state methods.
docs/api-reference/events-and-callbacks.md	Adds `Selection.rows(limit=None)` to the documented selection API.

_{Reviews (4): Last reviewed commit: "Fix test helper import ordering" | Re-trigger Greptile}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/check_public_api.py`:
- Around line 408-409: In the validation flow around build_public_api_inventory
and validate_declarative_api_contract, validate components_module.Chart and
__all__ before constructing the inventory. Return or otherwise stop inventory
construction when either guard reports invalid input, preserving the validation
errors instead of allowing dereference or getattr exceptions; add regression
coverage for a missing Chart and a non-string __all__ member.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: da885517-cebc-4d69-b52c-a3f64e365bc7

📥 Commits

Reviewing files that changed from the base of the PR and between 37c3d91 and 6186389.

📒 Files selected for processing (8)

Makefile
docs/api-reference/events-and-callbacks.md
docs/api-reference/figure-methods.md
scripts/check_public_api.py
scripts/verify_docs_local.py
scripts/verify_local.py
tests/test_public_api.py
tests/test_type_surface.py

cubic-dev-ai

All reported issues were addressed

_{Tip: instead of fixing issues one by one fix them all with cubic
Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 5 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic}

Enforce public API docs inventory

6186389

coderabbitai Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread scripts/check_public_api.py

Handle malformed public API inputs safely

5832887

cubic-dev-ai Bot reviewed Aug 5, 2026

View reviewed changes

coderabbitai Bot mentioned this pull request Aug 5, 2026

Fix/export sandbox security #459

Open

Harden public API documentation checks

2b595e0

cubic-dev-ai Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread tests/test_public_api.py Outdated

Comment thread docs/api-reference/figure-methods.md Outdated

Harsh Thakare added 2 commits August 5, 2026 14:09

Refine public API test helpers and notebook docs

a33490d

Fix test helper import ordering

8f45166

Uh oh!

Conversation

harsh21234i commented Aug 5, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

greptile-apps Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

harsh21234i commented Aug 5, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

greptile-apps Bot commented Aug 5, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading